<!DOCTYPE html>
<html lang="en">
<head>
  <title>Vert.x-redis - Vert.x</title>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta content="width=device-width, initial-scale=1.0" name="viewport">
  <meta content="Vert.x is a tool-kit for building reactive applications on the JVM." name="description">
  <link href="http://vertx.io/stylesheets/docs.css" media="screen" rel="stylesheet">
  <link href="http://vertx.io/stylesheets/font-awesome.min.css" media="screen" rel="stylesheet">
  <link href="http://vertx.io/javascripts/styles/rainbow.min.css" media="screen" rel="stylesheet">
  <!-- IE 6-8 support of HTML 5 elements -->
  <!--[if lt IE 9]>
  <script src="http://static.jboss.org/theme/js/libs/html5/pre3.6/html5.min.js"></script>
  <![endif]-->

  <link rel="apple-touch-icon" sizes="57x57" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-57x57.png">
  <link rel="apple-touch-icon" sizes="60x60" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-60x60.png">
  <link rel="apple-touch-icon" sizes="72x72" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-72x72.png">
  <link rel="apple-touch-icon" sizes="76x76" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-76x76.png">
  <link rel="apple-touch-icon" sizes="114x114" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-114x114.png">
  <link rel="apple-touch-icon" sizes="120x120" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-120x120.png">
  <link rel="apple-touch-icon" sizes="144x144" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-144x144.png">
  <link rel="apple-touch-icon" sizes="152x152" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-152x152.png">
  <link rel="apple-touch-icon" sizes="180x180" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-180x180.png">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-32x32.png" sizes="32x32">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/android-chrome-192x192.png" sizes="192x192">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-96x96.png" sizes="96x96">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-16x16.png" sizes="16x16">
  <link rel="manifest" href="http://vertx.io/assets/favicons/vertx-favicon-7/manifest.json">
  <link rel="mask-icon" href="http://vertx.io/assets/favicons/vertx-favicon-7/safari-pinned-tab.svg" color="#5bbad5">
  <meta name="msapplication-TileColor" content="#7d3194">
  <meta name="msapplication-TileImage" content="http://vertx.io/assets/favicons/vertx-favicon-7/mstile-144x144.png">
  <meta name="theme-color" content="#ffffff">

  <link href="http://fonts.googleapis.com/css?family=Ubuntu:400,500,700,400italic" rel="stylesheet" type="text/css">
  <link rel="alternate" type="application/rss+xml" title="RSS"
     href="http://vertx.io/feed.xml">
  <script>
    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
    })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
    ga('create', 'UA-30144458-1', 'auto');
    ga('create', 'UA-71153120-1', 'auto', 'tracker');
    ga('send', 'pageview');
    ga('tracker.send', 'pageview');
  </script>
</head>
<body>

<a href="http://www.reactivemanifesto.org/" id="reactive-manifesto-banner">
  <img style="border: 0; position: fixed; right: 0; top:0; z-index: 9000"
    src="http://d379ifj7s9wntv.cloudfront.net/reactivemanifesto/images/ribbons/we-are-reactive-black-right.png">
</a>

<a id="skippy" class="sr-only sr-only-focusable" href="#content"><div class="container"><span class="skiplink-text">Skip to main content</span></div></a>

<header class="navbar navbar-default navbar-static-top" id="top" role="banner">
  <div class="container">
    <div class="navbar-header">
      <button class="navbar-toggle collapsed" type="button" data-toggle="collapse" data-target="#vertx-navbar-collapse">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <a href="http://vertx.io/" class="navbar-brand"><img alt="Brand" src="http://vertx.io/assets/logo-sm.png"></a>
    </div>
    <nav class="collapse navbar-collapse" id="vertx-navbar-collapse">
      <ul class="nav navbar-nav navbar-right">
        <li><a href="http://vertx.io/download/">Download</a></li>
        <li><a href="http://vertx.io/docs/">Documentation</a></li>
        <li><a href="https://github.com/vert-x3/wiki/wiki">Wiki</a></li>
        <li><a href="http://vertx.io/community/">Community</a></li>
        <li><a href="http://vertx.io/materials/">Materials</a></li>
        <li><a href="http://vertx.io/blog/">Blog</a></li>        
      </ul>
    </nav>
  </div>
</header>



  <div class="page-header" id="content">
    <div class="container">
      <div class="row">
        <div class="col-sm-12">
          <h1>Vert.x-redis</h1>
          
        </div>
      </div>
    </div>
  </div>




<div id="content">
  <div class="container docs-content">
    <div class="row">
      <div class="col-sm-12 col-md-push-9 col-md-3 hidden-xs hidden-sm">
        <div id="sidebar" data-spy="affix">
          <ul class="sectlevel1">
<li><a href="#_using_vert_x_redis">Using Vert.x-Redis</a></li>
<li><a href="#_connecting_to_redis">Connecting to Redis</a></li>
<li><a href="#_running_commands">Running commands</a></li>
<li><a href="#_pub_sub_mode">Pub/Sub mode</a></li>
<li><a href="#_friendlier_hash_commands">Friendlier hash commands</a>
<ul class="sectlevel2">
<li><a href="#_command_hgetall">Command hgetall</a></li>
<li><a href="#_command_mset">command mset</a></li>
<li><a href="#_command_msetnx">command msetnx</a></li>
<li><a href="#_command_hmset">command hmset</a></li>
<li><a href="#_command_zadd">command zadd</a></li>
</ul>
</li>
<li><a href="#_server_info">Server Info</a></li>
<li><a href="#_eval_and_evalsha">Eval and Evalsha</a></li>
</ul>
        </div>
      </div>
      <div class="col-sm-12 col-md-pull-3 col-md-9">
        <div class="toc hidden-md hidden-lg">
          <h2>Table of Contents</h2>
          <ul class="sectlevel1">
<li><a href="#_using_vert_x_redis">Using Vert.x-Redis</a></li>
<li><a href="#_connecting_to_redis">Connecting to Redis</a></li>
<li><a href="#_running_commands">Running commands</a></li>
<li><a href="#_pub_sub_mode">Pub/Sub mode</a></li>
<li><a href="#_friendlier_hash_commands">Friendlier hash commands</a>
<ul class="sectlevel2">
<li><a href="#_command_hgetall">Command hgetall</a></li>
<li><a href="#_command_mset">command mset</a></li>
<li><a href="#_command_msetnx">command msetnx</a></li>
<li><a href="#_command_hmset">command hmset</a></li>
<li><a href="#_command_zadd">command zadd</a></li>
</ul>
</li>
<li><a href="#_server_info">Server Info</a></li>
<li><a href="#_eval_and_evalsha">Eval and Evalsha</a></li>
</ul>
        </div>
        <div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>Vert.x-redis is redis client to be used with Vert.x.</p>
</div>
<div class="paragraph">
<p>This module allows data to be saved, retrieved, searched for, and deleted in a Redis. Redis is an open source, BSD
licensed, advanced key-value store. It is often referred to as a data structure server since keys can contain
strings, hashes, lists, sets and sorted sets. To use this module you must have a Redis server instance running on
your network.</p>
</div>
<div class="paragraph">
<p>Redis has a rich API and it can be organized in the following groups:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Cluster - Commands related to cluster management, note that using most of these commands you will need a redis server with version &gt;=3.0.0</p>
</li>
<li>
<p>Connection - Commands that allow you to switch DBs, connect, disconnect and authenticate to a server.</p>
</li>
<li>
<p>Hashes - Commands that allow operations on hashes.</p>
</li>
<li>
<p>HyperLogLog - Commands to approximating the number of distinct elements in a multiset, a HyperLogLog.</p>
</li>
<li>
<p>Keys - Commands to work with Keys.</p>
</li>
<li>
<p>List - Commands to work with Lists.</p>
</li>
<li>
<p>Pub/Sub - Commands to create queues and pub/sub clients.</p>
</li>
<li>
<p>Scripting - Commands to run Lua Scripts in redis.</p>
</li>
<li>
<p>Server - Commands to manage and get server configurations.</p>
</li>
<li>
<p>Sets - Commands to work with un ordered sets.</p>
</li>
<li>
<p>Sorted Sets - Commands to work with sorted sets.</p>
</li>
<li>
<p>Strings - Commands to work with Strings.</p>
</li>
<li>
<p>Transactions - Commands to handle transaction lifecycle.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_using_vert_x_redis">Using Vert.x-Redis</h2>
<div class="sectionbody">
<div class="paragraph">
<p>To use the Vert.x Redis client, add the following dependency to the <em>dependencies</em> section of your build descriptor:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Maven (in your <code>pom.xml</code>):</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-xml" data-lang="xml">&lt;dependency&gt;
  &lt;groupId&gt;io.vertx&lt;/groupId&gt;
  &lt;artifactId&gt;vertx-redis-client&lt;/artifactId&gt;
  &lt;version&gt;3.3.3&lt;/version&gt;
&lt;/dependency&gt;</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>Gradle (in your <code>build.gradle</code> file):</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-groovy" data-lang="groovy">compile 'io.vertx:vertx-redis-client:3.3.3'</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_connecting_to_redis">Connecting to Redis</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In order to connect to Redis there is a config required. This config is provided in the form of <code><a href="../../apidocs/io/vertx/redis/RedisOptions.html">RedisOptions</a></code>
containing the following values:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>host</code>: default is <code>localhost</code></p>
</li>
<li>
<p><code>port</code>: default is <code>6379</code></p>
</li>
<li>
<p><code>encoding</code>: default is <code>UTF-8</code></p>
</li>
<li>
<p><code>tcpKeepAlive</code>: default <code>true</code></p>
</li>
<li>
<p><code>tcpNoDelay</code>: default <code>true</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>An connection example can then be:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">RedisOptions config = new RedisOptions()
    .setHost("127.0.0.1");

RedisClient redis = RedisClient.create(vertx, config);</code></pre>
</div>
</div>
<div class="paragraph">
<p>The client attempts to reconnect to the server on connection errors, for this reason if you are connecting to a server
that requires authentication and/or you are not using the default database you must provide the authentication
password and/or database id to the config object, the properties names are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>auth</code></p>
</li>
<li>
<p><code>select</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>If you do not do this and manually call the <code><a href="../../apidocs/io/vertx/redis/RedisClient.html#auth-java.lang.String-io.vertx.core.Handler-">auth</a></code>
or <code><a href="../../apidocs/io/vertx/redis/RedisClient.html#select-int-io.vertx.core.Handler-">select</a></code> then the client will not know how to recover
the connection in case of socket error.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_running_commands">Running commands</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Given that the redis client is connected to the server, all commands are now possible to execute using this module.
The module offers a clean API for executing commands without the need to hand write the command itself, for example
if one wants to get a value of a key it can be done as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">RedisClient redis = RedisClient.create(vertx, new RedisOptions());

redis.get("mykey", res -&gt; {
  if (res.succeeded()) {
    // so something...
  }
});</code></pre>
</div>
</div>
<div class="paragraph">
<p>In order to know more about the commands available you should look at: &lt;a href="http://redis.io/commands"&gt;redis documentation&lt;/a&gt;.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_pub_sub_mode">Pub/Sub mode</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Redis supports queues and pub/sub mode, when operated in this mode once a connection invokes a subscriber mode then
it cannot be used for running other commands than the command to leave that mode.</p>
</div>
<div class="paragraph">
<p>To start a subscriber one would do:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">vertx.eventBus().&lt;JsonObject&gt;consumer("io.vertx.redis.channel1", received -&gt; {
  // do whatever you need to do with your message
  JsonObject value = received.body().getJsonObject("value");
  // the value is a JSON doc with the following properties
  // channel - The channel to which this message was sent
  // pattern - Pattern is present if you use psubscribe command and is the pattern that matched this message channel
  // message - The message payload
});

RedisClient redis = RedisClient.create(vertx, new RedisOptions());

redis.subscribe("channel1", res -&gt; {
    if (res.succeeded()) {
        // so something...
    }
});</code></pre>
</div>
</div>
<div class="paragraph">
<p>And from another place in the code publish messages to the queue:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">RedisClient redis = RedisClient.create(vertx, new RedisOptions());

redis.publish("channel1", "Hello World!", res -&gt; {
    if (res.succeeded()) {
        // so something...
    }
});</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_friendlier_hash_commands">Friendlier hash commands</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Most Redis commands take a single String or an Array of Strings as arguments, and replies are sent back as a single
String or an Array of Strings. When dealing with hash values, there are a couple of useful exceptions to this.</p>
</div>
<div class="sect2">
<h3 id="_command_hgetall">Command hgetall</h3>
<div class="paragraph">
<p>The reply from an hgetall command will be converted into a JSON Object. That way you can interact with the responses
using JSON syntax which is handy for the EventBus communication.</p>
</div>
</div>
<div class="sect2">
<h3 id="_command_mset">command mset</h3>
<div class="paragraph">
<p>Multiple values in a hash can be set by supplying an object. Note however that key and value will be coerced to
strings.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>{
  keyName: "value",
  otherKeyName: "other value"
}</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_command_msetnx">command msetnx</h3>
<div class="paragraph">
<p>Multiple values in a hash can be set by supplying an object. Note however that key and value will be coerced to
strings.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>{
  keyName: "value",
  otherKeyName: "other value"
}</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_command_hmset">command hmset</h3>
<div class="paragraph">
<p>Multiple values in a hash can be set by supplying an object. Note however that key and value will be coerced to
strings.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>{
  keyName: "value",
  otherKeyName: "other value"
}</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_command_zadd">command zadd</h3>
<div class="paragraph">
<p>Multiple values in a hash can be set by supplying an object. Note however that key and value will be coerced to
strings.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>{
  score: "member",
  otherScore: "other member"
}</pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_server_info">Server Info</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In order to make it easier to work with the info response you don&#8217;t need to parse the data yourself and the module
will return it in a easy to understand JSON format. The format is as follows: A JSON object for each section filled
with properties that belong to that section. If for some reason there is no section the properties will be visible
at the top level object.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>{
  server: {
    redis_version: "2.5.13",
    redis_git_sha1: "2812b945",
    redis_git_dirty: "0",
    os: "Linux 2.6.32.16-linode28 i686",
    arch_bits: "32",
    multiplexing_api: "epoll",
    gcc_version: "4.4.1",
    process_id: "8107",
    ...
  },
  memory: {...},
  client: {...},
  ...
}</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_eval_and_evalsha">Eval and Evalsha</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Eval and Evalsha commands are special due to its return value can be any type. Vert.x is built on top of Java and the
language adheres to strong typing so returning any type turns to be problematic since we want to avoid having <code>Object</code>
type being used. The reason to avoid the type <code>Object</code> is that we also are polyglot and the conversion between
languages would become rather complicated and hard to implement. For all these reasons the commands eval and evalsha
will always return a JsonArray, even for example for scripts such as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code>return 10</code></pre>
</div>
</div>
<div class="paragraph">
<p>In this case the return value will be a json array with the value 10 on index 0.</p>
</div>
</div>
</div>

        

        
          <div id="footer">
            <div id="footer-text">
              
                Last updated 2016-09-12 08:38:04 CEST
              
              
            </div>
          </div>
        
      </div>
    </div>
  </div>
</div>

<footer>
  <div class="container">
    <div class="row">
      <div class="col-xs-6 col-sm-3 col-md-3 col-lg-2">
        <h2>Vert.x</h2>
        <ul class="list-unstyled">
          <li><a href="http://vertx.io/">Home</a></li>
          <li><a href="http://vertx.io/download/">Download</a></li>
          <li><a href="http://vertx.io/docs/">Documentation</a></li>
          <li><a href="https://github.com/vert-x3/wiki/wiki">Wiki</a></li>
          <li><a href="http://vertx.io/blog/">Blog</a></li>
          <li><a href="http://vertx.io/vertx2/" class="vertx-2-link">Vert.x 2</a></li>
        </ul>
      </div>
      <div class="col-xs-6 col-sm-3 col-md-3 col-lg-2">
        <h2>Community</h2>
        <ul class="list-unstyled">
          <li><a href="http://vertx.io/community/">Help &amp; Contributors</a></li>
          <li><a href="http://vertx.io/materials/">Learning materials</a></li>
          <li><a href="https://groups.google.com/forum/?fromgroups#!forum/vertx">User Group</a></li>
          <li><a href="https://groups.google.com/forum/?fromgroups#!forum/vertx-dev">Developer Group</a></li>
        </ul>
      </div>

      <div class="col-xs-12 col-sm-6 col-lg-offset-2 col-md-6 copyright">
        <p>Vert.x is open source and dual licensed under the <a href="https://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License 1.0</a> and <a href="https://www.apache.org/licenses/LICENSE-2.0.html">Apache License 2.0</a>.</p>
        <p>This website is licensed under the <a href="http://creativecommons.org/licenses/by-sa/3.0/">CC BY-SA 3.0 License</a>.<br>
        Design by <a href="http://www.michel-kraemer.com">Michel Kr&auml;mer</a>. <a href="http://www.entypo.com">Entypo pictograms</a> by Daniel Bruce.</p>
        <div class="row">
          <div class="col-xs-12 col-lg-offset-1 col-md-5">
            <a href="http://eclipse.org">
            <img class="logo eclipse-logo" src="http://vertx.io/assets/eclipse_logo_grey_small.png" width="204" height="48">
            </a>
          </div>
          <div class="col-xs-12 col-md-offset-2 col-lg-offset-0 col-md-5">
            <a href="http://cloudbees.com">
            <img class="logo cloudbees-logo" src="http://vertx.io/assets/Button-Built-on-CB-1-grey.png" width="180" height="48">
           </a>
          </div>
          <div class="col-xs-12 col-md-offset-2 col-lg-offset-1 col-md-5 jprofiler">
            <a href="http://www.ej-technologies.com/products/jprofiler/overview.html"
            style="text-decoration:none">
            <img class="logo jprofiler-logo" src="http://vertx.io/assets/jprofiler-logo.png" width="48" height="48"><span class="jprofiler-logo">&nbsp; JPROFILER</span>
            </a>
          </div>
        </div>
      </div>
    </div>
  </div>
</footer>

<script src="http://static.jboss.org/theme/js/libs/jquery/jquery-1.9.1.min.js"></script>
<script src="http://vertx.io/javascripts/bootstrap.min.js"></script>
<script src="http://vertx.io/javascripts/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>



<script src="http://vertx.io/javascripts/sidebar.js"></script>


</body>
</html>
